home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Users Group Library 1996 July / C-C++ Users Group Library July 1996.iso / vol_400 / 422_04 / help.doc < prev    next >
Text File  |  1994-02-14  |  9KB  |  221 lines
  1. HELP is a command line help utility, which is considerably more
  2. powerful than the 'help' command supplied with DOS (version 5).
  3.  
  4. Its main features are:
  5.  
  6.  - Completely hierarchical structure of topics and sub-topics.
  7.  - Interactive or command line operation.
  8.  - Supports multiple help "libraries", allowing you to maintain
  9.    and access help text for different applications separately.
  10.  - Files are indexed for ultra-fast operation.
  11.  - Help text can be compressed to reduce disk storage.
  12.  - Includes "Help File Compiler", for creating your own help libraries.
  13.  
  14. HELP may be freely distributed without payment or royalty.
  15.  
  16. The help library files used by HELP contain an indexed dictionary of all
  17. topics, which contains pointers to help text contained in the remainder of
  18. the file. This allows ultra-fast access to topics and sub-topics, however
  19. it causes the file to be unreadable as a standard ASCII file, and therefore
  20. not directly editable.
  21.  
  22. Library files for HELP are prepared in "source" form, and then compiled
  23. into the above format using the "Help File Compiler" utility (HFC.COM)
  24. which is included in this package. The compiler also has the option to
  25. compress the text as it is compiled.
  26.  
  27. If a library is not specified in the help command line (type 'help ?' for
  28. details), HELP assumes the library 'GENERAL'(.HLP) is to be used.
  29.  
  30. Before HELP looks for a library file, it first checks for the environment
  31. variable 'HELP'. If this variable is defined, HELP assumes that it contains
  32. the directory path to the help library files. If the variable is not defined,
  33. HELP looks in the directory from which it was loaded. For DOS versions prior
  34. to 3.0, you should always define the HELP environment variable, otherwise
  35. HELP may not be able to locate its library.
  36.  
  37. If a library file cannot be found, or help is invoked with the '?' or '/?'
  38. parameter, it displays a short usage summary, and the names of all libraries
  39. which are available.
  40.  
  41.  
  42. Source File Format:
  43. ------------------
  44. Each topic or sub-topic is identified by a line beginning with one or more
  45. '>' characters. The number of '>'s that occur identify the topic level. Each
  46. topic is considered to contain all other topics and sub-topics that follow,
  47. until another topic of equal or lower level is encountered.
  48.  
  49. IMMEDIATELY following the '>'s, is the name of the topic, which will
  50. be presented as "Additional information available" to the next higher
  51. topic level.
  52.  
  53. Following the name, (delimited by a space or tab), the remainder of the
  54. line is used as a "title". The entire line is displayed when traversing
  55. downward into a sub-topic. Each title is indented by one space when
  56. proceeding to the current sub-topic level.
  57.  
  58. Following the topic line, is the text of the help topic. It continues
  59. until another line beginning with '>' is encountered, or the end of
  60. file occurs.
  61.  
  62. The text at the beginning of the file (before the first '>'), is
  63. considered topic level 0, and is displayed upon entry to the help
  64. library.
  65.  
  66. For a complete example, see the source file SAMPLE.SRC. You may
  67. compile this into a library (.HLP) file, with the command:
  68.  
  69.          HFC sample.src sample.hlp
  70.  
  71. You may then execute HELP, and see what the result looks like, with
  72. the command:
  73.  
  74.          HELP/SAMPLE
  75.  
  76. When HELP prompts you for a topic or subtopic, you may enter:
  77.  
  78.    1 - A name from the displayed list, to display that topic or sub-topic.
  79.        HELP will also accept a partial name, and displays the first entry
  80.        that begins with the characters you enter.
  81.  
  82.    2 - A blank line to backup to the previous help level. If a blank
  83.        line is entered at the main "Topic?" prompt, HELP terminates.
  84.  
  85.    3 - A '?' to re-display the current topic or sub-topic.
  86.  
  87. A larger example of a DOS help file is also included, try compiling
  88. it with:
  89.  
  90.          HFC DOS.SRC GENERAL.HLP
  91.  
  92. Since GENERAL is the default help library, you can access this help
  93. simply with:
  94.  
  95.          HELP
  96.  
  97. Note: The DOS help source shows how easily you can create a help library
  98. from another source of ASCII text. Most of the command descriptions were
  99. generated with "command/? >>file", and then edited slightly to add the
  100. topic headers etc.
  101.  
  102.  
  103. Compression:
  104. -----------
  105. If you add the '-compress' option to the end of the HFC command line, the
  106. text will be compressed as it is added to the help library. The operation
  107. of HFC with compression is *VERY* slow, however you only have to do it once.
  108. The operation of HELP is not slowed when the file is compressed (in fact
  109. is is slightly speeded up).
  110.  
  111. Since the help file is not accessed in a sequential fashion, and the
  112. individual topic contents are often small, a dynamic dictionary type of
  113. compression such as "LZW" is not suitable. The help file compiler uses
  114. two simple but reasonably effective compression methods:
  115.  
  116. 1 - Run length encoding
  117.  
  118. Sequences of three or more identical characters are automatically
  119. compressed into two code sequences. Up to 45 identical characters
  120. may represented by a single two code sequence. If more than 45
  121. charactes are found, HFC will process then as two or more separate
  122. run length codes.
  123.  
  124. 2 - Static dictionary encoding
  125.  
  126. HFC and HELP each contain an identical dictionary of common character
  127. sequences likely to occur in help text. Whenever HFC encounters a sequence
  128. which occurs in the dictionary, it encodes a single byte code that identifies
  129. the dictionary location to HELP, which upon encountering the value, will
  130. insert the apropriate entry in the output text.
  131.  
  132. If you specify the '-report' option to HFC, it will report on the
  133. frequency of each dictionary entry, and the total number of bytes saved
  134. by using that entry. Although this was implemented mainly as a way for me
  135. to check the efficency of the dictionary, it is also  a good way to find
  136. out exactly what entries are in the dictionary.
  137.  
  138.     eg: HFC sample.src sample.hlp -c -r
  139.  
  140. Note: If you use '-report' without '-compress', HFC reports that all
  141. entries are unused.
  142.  
  143.  
  144. Limitations:
  145. -----------
  146. The architecture of an individual HELP library is limited to a maximum of 255
  147. total topics and subtopics, and a maximum of 64K total help text (not counting
  148. topic names and titles, which are stored separately). When using compression,
  149. the amount of text increases, as only the compressed data has to fit in 64K.
  150. To assist you in keeping an eye on this, the Help File Compiler (HFC.COM)
  151. reports the amount of actual text data written to the output file.
  152.  
  153. Since HELP supports multiple libraries, you can have virtually unlimited
  154. help information, however you have to partition it into 64K chunks.
  155.  
  156. Help topic names should be 14 characters or less. (15 is allowed, however
  157. they will run together in the screen display).
  158.  
  159. Help topics may be nested to a maximum of 25 levels deep.
  160.  
  161.  
  162. Installation:
  163. ------------
  164. Since DOS 5 includes a HELP command, there is a potential conflict in
  165. the command names. There are several ways to resolve this:
  166.  
  167. 1) Replace DOS's HELP.EXE with HELP.COM. Since I have provided a DOS help
  168.    file, the old HELP command is not really necessary.
  169.  
  170. 2) Rename DOS's HELP.EXE to DOSHELP.EXE or something similar.
  171.  
  172. 3) Rename HELP.COM.
  173.  
  174. 4) Insure the directory containing HELP.COM occurs first in your path.
  175.    You can still execute the DOS help command by using the entire path
  176.    eg: \dos\help
  177.  
  178. 5) If using HELP with a single application, place HELP.COM in the same
  179.    directory as that application. When in the directory, HELP.COM will
  180.    be available, otherwise DOS's HELP.EXE will be used.
  181.  
  182.  
  183. Distribution:
  184. ------------
  185. One of the best ways in which to "help" users, is to have a consistant
  186. method by which they can optain information about the applications that
  187. they use.
  188.  
  189. For this reason, I offering HELP completely free of charge, and am placing
  190. no restrictions whatsoever on the redistribution of the HELP.COM and/or
  191. HFC.COM included in this archive. I encourage software developers to use
  192. HELP to provide online information about their products.
  193.  
  194. I do claim copyright to the code, only for the purpose of restricting
  195. modification. You may not r